<!DOCTYPE HTML>
<html>
<head>
<title>Roundtrip plugin API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>Roundtrip plugin API</h1>
<p>
The roundtrip plugin measures page load time, or other timers associated with the page.  Its API
is encapsulated within the <code>BOOMR.plugins.RT</code> namespace.
</p>

<h2 id="methods">Methods</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
Called by the <a href="BOOMR.html#init">BOOMR.init()</a> method to configure the roundtrip
plugin.  The configuration object is described in <a href="../howtos/howto-6.html">Howto #6 &mdash; Configuring boomerang</a>.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>

<dt>startTimer(sName)</dt>
<dd>
<p>
Starts the timer named <code>sName</code>.  Timers count in milliseconds.  You must call
<code>endTimer()</code> when this timer has complete for the measurement to be recorded
in boomerang's beacon.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-4.html">Howto #4</a> for an example that uses startTimer and endTimer.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>

<dt>endTimer(sName, nValue)</dt>
<dd>
<p>
Stops the timer named <code>sName</code>.  It is not necessary for the timer to have been started
before you call <code>endTimer()</code>.  If a timer with this name was not started, then the unload
time of the previous page is used instead.  This allows you to measure the time across pages.
</p>
<h3>Parameters:</h3>
<dl>
<dt>sName</dt>
<dd>The name of the timer to stop</dd>

<dt>nValue</dt>
<dd><strong>[optional]</strong>
A javascript timestamp value (milliseconds since the epoch).  If set, the timer's stop time will be set
explicitly to this value.  If not set, the current timestamp is used.  You'd use this parameter if you
measured a timestamp before <code>boomerang</code> was loaded and now need to pass that value to the
roundtrip plugin.
</dd>
</dl>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-4.html">Howto #4</a> for an example that uses startTimer and endTimer.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>

<dt>setTimer(sName, nValue)</dt>
<dd>
<p>
Sets the timer named <code>sName</code> to an explicit time measurement.  You'd use this method if you
measured time values within your page before <code>boomerang</code> was loaded and now need to pass
those values to the roundtrip plugin for inclusion in the beacon.  It is not necessary to call
<code>startTimer()</code> or <code>endTimer()</code> before calling <code>setTimer()</code>.  If you
do, the old values will be ignored and the value passed in to this function will be used.
</p>
<h3>Parameters:</h3>
<dl>
<dt>sName</dt>
<dd>The name of the timer to set</dd>

<dt>nValue</dt>
<dd>
The value in milliseconds to set this timer to.
</dd>
</dl>

<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>

<dt>done()</dt>
<dd>
<p>
Typically called automatically when boomerang's <a href="BOOMR.html#page_ready">page_ready</a>
event fires, but it may also be called explicitly to measure the load time of transitions that
do not involve a onload event.
</p>
<p>
This method calculates page load time, and determines whether the values we have are good enough
to be beaconed.  It then signals the <code>BOOMR</code> object via its <a href="BOOMR.html#sendBeacon">sendBeacon</a>
method.
</p>

<h3>Example:</h3>
<p>
See <a href="../howtos/howto-2.html">Howto #2</a> for an example of explicitly calling the <code>done()</code> method.
</p>

<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>

<h3>See also</h3>
<ul>
<li><a href="../methodology.html#roundtrip">Roundtrip methodology</a> for details on how roundtrip time is measured.</li>
</ul>
</dd>

<dt>is_complete()</dt>
<dd>
<p>
Called by <a href="BOOMR.html#sendBeacon">BOOMR.sendBeacon()</a> to determine if the roundtrip plugin has
finished what it's doing or not.
</p>
<h3>Returns</h3>
<ul>
<li><code>true</code> if the plugin has completed.</li>
<li><code>false</code> if the plugin has not completed.</li>
</ul>
</dd>

</dl>

<p>
The latest code and docs is available on <a href="http://github.com/yahoo/boomerang/">github.com/yahoo/boomerang</a>
</p>

</body>
</html>
